docs(agents): propose explicit init and add commands#9135
Conversation
|
Azure Pipelines: 20 pipeline(s) were filtered out due to trigger conditions. There may be pipelines that require an authorized user to comment /azp run to run. |
microsoft-github-policy-service
Bot
added
the
customer-reported
|
Thank you for your contribution @hund030! We will review the pull request and get back to you soon. |
There was a problem hiding this comment.
Pull request overview
Proposes separating agent project creation from adding agents to existing projects.
Changes:
- Defines
agent initandagent addcontracts. - Documents source selection and
--infrabehavior. - Records scope and compatibility decisions.
| ### Sources | ||
|
|
||
| ```text | ||
| --template |
| | `init` | No | Yes | Yes | Initialize, then generate IaC. | | ||
| | `init` | No | No | No | Interactive: choose source; non-interactive: fail. | | ||
| | `init` | No | No | Yes | Interactive: choose source, initialize, generate IaC; non-interactive: fail. | | ||
| | `init` | Yes | No | Yes | Generate IaC only. | |
| add + source -> validate existing project -> merge/register agent | ||
| ``` | ||
|
|
||
| Both `init` and `add` share source resolution and agent-registration logic. Registration merges the complete service graph instead of replacing existing Foundry services one at a time. The detailed engineering design defines concurrency, retry, and compatibility mechanics. |
|
|
||
| 3. **Should `init` ever automatically call `add` when it finds a project?** Proposed: No. Fail before mutation and print the exact replacement command. | ||
|
|
||
| 4. **Should existing positional and `--src` forms remain temporarily?** Proposed: Yes, with deprecation warnings and deterministic translation to the new source options. |
jongio
left a comment
jongio
left a comment
There was a problem hiding this comment.
One consistency gap I didn't see raised yet, noted inline on the decision table.
| | `init` | No | Yes | Yes | Initialize, then generate IaC. | | ||
| | `init` | No | No | No | Interactive: choose source; non-interactive: fail. | | ||
| | `init` | No | No | Yes | Interactive: choose source, initialize, generate IaC; non-interactive: fail. | | ||
| | `init` | Yes | No | Yes | Generate IaC only. | |
There was a problem hiding this comment.
The behavioral rules scope IaC-only to an existing compatible project (lines 110-111), and Non-scope rejects unsafe shapes like Aspire projects or multiple Foundry project services. This table only keys on Project found, so init --infra against an incompatible existing project resolves to Generate IaC only here instead of failing. Consider carrying the compatibility gate into the table (or a note) so an unsupported project shape maps to a fail-with-guidance result rather than IaC generation.
microsoft-github-policy-service
Bot
added
the
no-recent-activity
|
Hi @@hund030. Thank you for your interest in helping to improve the Azure Developer CLI experience and for your contribution. We've noticed that there hasn't been recent engagement on this pull request. If this is still an active work stream, please let us know by pushing some changes or leaving a comment. Otherwise, we'll close this out in 7 days. |
jongio
left a comment
jongio
left a comment
There was a problem hiding this comment.
One structural note on the two decision surfaces, inline.
| |---|---:|---:|---:|---| | ||
| | `init` | No | Yes | No | Initialize project and agent. | | ||
| | `init` | No | Yes | Yes | Initialize, then generate IaC. | | ||
| | `init` | No | No | No | Interactive: choose source; non-interactive: fail. | |
There was a problem hiding this comment.
The Behavioral rules table above and this Decision table encode the same init/add contract with different columns, and they've already drifted. Behavioral rules restrict standalone --infra to an existing compatible project (lines 116-117), but this table's init | Yes | No | Yes row drops the compatibility qualifier and just says IaC only. The missing bare init in an existing project row that others flagged is the same failure mode. Two hand-maintained tables for one contract will keep diverging as the design evolves. Consider making one the single source of truth and deriving or dropping the other.
Summary
Design proposal for #8383.
azd ai agent initcurrently creates or modifies projects based on directory context, making behavior difficult to predict and debug.Changes
agent init/add contract: separate new-project initialization from adding agents to existing projects.--infracompatibility: retain post-init and standalone IaC generation with explicit decision rules.review decisions: document scope, migration behavior, command matrix, and open product questions.